…ifest

Filed alongside the 8 launcher-standard PRs (#170, #171, #172, #173,
#175, #176, #177, #179) so reviewers landing on any individual PR
can find the full picture in one place.

Two files following the existing `docs/audits/` convention:

- launcher-standard-review-2026-05-26.adoc — prose narrative for
  humans. Headline findings table (class × finding × addressed-in PR),
  PR map (number, branch, files, class), what-this-campaign-produces
  summary, deferred follow-ups, method notes including the
  parallel-session amend incident and how recovery worked.

- launcher-standard-review-2026-05-26.a2ml — machine-readable manifest
  for tooling (PR-batching bots, change-impact analyzers,
  launch-scaffolder regenerators). Same PR set as parseable A2ML:
  per-PR file lists, addressed-issues, new-files lists, new-a2ml-keys
  lists, plus coordination notes (spec-version conflict resolution,
  lock-step gate trigger map) and deferred-followups with gating
  conditions. Includes a session-lessons-captured block pointing at
  the two memory entries written during this campaign.

Pattern matches existing gap-matrix-2026-04-17.a2ml (A2ML extension
syntax including @abstract: block). Pure tomllib does NOT parse A2ML;
the repo's A2ML tooling does.

Signing-key fingerprint deliberately NOT recorded inline — gitleaks's
generic-api-key rule misclassifies 40-char PGP fingerprints as
secrets. The all-prs-gpg-signed flag is the load-bearing assertion;
the fingerprint is recoverable from `git log --show-signature` if
anyone needs to verify against a specific key.

Independent of all 8 review PRs — touches only docs/audits/.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…#176)

## Summary

`keepopen.sh` always emitted ANSI colour escapes — even when the user
redirected output to a file or pipeline, and even when `NO_COLOR=1`
was set. [no-color.org](https://no-color.org/) has been the canonical
opt-out env var since 2017; respecting it is one of the cheapest UX
wins available.

## Change

At the top of `keepopen.sh`, if either `NO_COLOR` is set OR stdout is
not a TTY, all colour variables become empty strings. Banners and
prefix labels become plain text — still loud and clearly labelled,
just without escapes.

\`\`\`bash
if [[ -n "${NO_COLOR:-}" ]] || [[ ! -t 1 ]]; then
    C_RED='' C_YEL='' C_CYA='' C_GRN='' C_BOLD='' C_RST=''
else
    # original ANSI definitions
fi
\`\`\`

## Verified

\`\`\`
$ NO_COLOR=1 keepopen.sh testapp /tmp false false | grep -c $'\033'
0
$ keepopen.sh testapp /tmp false false | grep -c $'\033' # piped → not
TTY
0
\`\`\`

Desktop-launch path keeps colour (real terminal, no `NO_COLOR`), so
the on-screen failure banners are unchanged. The new behaviour only
fires when:

- User has `NO_COLOR` set globally (their explicit preference), or
- Output is piped to a file / capture (CI logs, `tee`, `.log`
  redirects)

## Scope

Touches `launcher/keepopen.sh` only — not part of the
a2ml↔adoc lock-step group, so the gate in #172 does not fire on this
PR.

## Coordination

Independent of all other open launcher-standard PRs (#170, #171,
#172, #173, #175) — different file, no conflicts in any merge order.

## Test plan

- [x] `NO_COLOR=1` produces zero ANSI escapes
- [x] Pipe (non-TTY stdout) produces zero ANSI escapes
- [x] Default TTY behaviour unchanged (loud red/yellow banners)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…-chain (#179)

## Summary

The a2ml declared `[soft-attach]` and `[error-visibility]` contracts
but provided no reference implementations. Every downstream launcher
had to re-implement the "if-installed-then-invoke" pattern and the
GUI dialog ladder — guaranteed drift, and a common reason downstream
launchers either skip these features (silent failures stay silent) or
implement them inconsistently.

This adds two sourceable bash helpers in `launcher/`, mirroring the
contract semantics from the a2ml, plus prose with graceful-degradation
usage patterns.

## `launcher/gui-error.sh`

`hp_gui_error "title" "message"`:

| Condition | Behaviour |
|-----------|-----------|
| Always | Write `[title] message` to stderr |
| stderr is TTY or `NO_GUI_ERROR=1` | stderr only, return 0 |
| no `\$DISPLAY` and no `\$WAYLAND_DISPLAY` | return 1 (cannot show GUI)
|
| Else | Try `kdialog → zenity → notify-send → xmessage`; first success
wins |

Mirrors `[error-visibility].gui-dialog-chain` exactly. Verified
locally: `NO_GUI_ERROR=1 ./launcher/gui-error.sh "T" "M"` → stderr
"[T] M", exit 0.

## `launcher/soft-attach.sh`

Three primitives mirroring the three shapes in `[soft-attach].tools`:

\`\`\`bash
hp_soft_attach_present "command"          # 0 if on PATH
hp_soft_attach_run "command line" # run if first token present, silent
no-op + 0 if missing
hp_soft_attach_event "tool" "event-name" [args] # `tool emit event-name
args` if present, silent no-op if missing
\`\`\`

All non-fatal — missing tools never break the launcher (per the
§soft-attach spec: *"called if present, silently skipped if absent"*).
CLI mode for ad-hoc use:

\`\`\`
./soft-attach.sh run "hypatia diagnose --app foo"
./soft-attach.sh event feedback-o-tron launcher:start_failed
./soft-attach.sh present hypatia
\`\`\`

## a2ml contract additions

`[error-visibility]`:
- `reference-impl = "launcher/gui-error.sh"` (pointer)
- `suppress-env-var = "NO_GUI_ERROR"` (formalises the override name)

`[soft-attach]`:
- `reference-impl = "launcher/soft-attach.sh"` (pointer)
- Each `tools` entry now carries explicit `style`
  (`"event" | "command"`) and `trigger` (e.g. `"on-start-failed"`) so
  launchers know **WHEN** to invoke each tool, not just **HOW**.
  Previously only `feedback-o-tron` had an explicit failure trigger.

## Prose additions (`launcher-standard.adoc`)

- §Error Handling: rewritten with `hp_gui_error` integration, graceful
  degradation pattern, and a NOTE on stderr-always behaviour
- §Soft-Attach (new subsection): documents the three primitives, the
  graceful-degradation source pattern, and an example `on_start_failed`
  hook wiring all three default tools

## Test plan

- [x] a2ml parses (python tomllib); new fields round-trip cleanly
- [x] Both helpers pass `bash -n`
- [x] `hp_gui_error` writes stderr + respects `NO_GUI_ERROR`
- [x] `hp_soft_attach_present` returns 0/1 correctly
- [x] `hp_soft_attach_run` runs installed, silently skips missing
- [x] `hp_soft_attach_event` silently skips missing tool
- [ ] Manual dialog test (deferred — requires KDE/GNOME desktop;
      logic matches well-documented invocation conventions per each
      dialog's man page)
- [ ] Lock-step gate (#172) goes green on first push (both files in
diff)

## Coordination

Independent of #170, #171, #172, #173, #175, #176, #177 — no file
overlap. Builds on the resolution ladder shipped in #171
(`hp_resolve_desktop_tools` is referenced in the prose examples) so
the new helpers are findable wherever `.desktop-tools/` resolves.
Both work standalone or via the ladder.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…ifest (#182)

## Summary

Documentation companion to the 8 launcher-standard PRs filed today
(#170, #171, #172, #173, #175, #176, #177, #179). Two files following
the existing `docs/audits/` convention:

| File | Audience | Purpose |
|------|----------|---------|
| `launcher-standard-review-2026-05-26.adoc` | Humans | Prose narrative
— headline findings table (class × finding × addressed-in PR), full PR
map, what-this-campaign-produces summary, deferred follow-ups, method
notes |
| `launcher-standard-review-2026-05-26.a2ml` | Machines | Parseable
manifest — per-PR file lists, addressed-issues, new-files,
new-a2ml-keys, coordination notes (spec-version conflict resolution,
lock-step gate trigger map), deferred-followups with gating conditions |

Reviewers landing on any individual PR can find the full picture in
one place.

## Why this exists

After 8 PRs the campaign story is spread across 8 PR bodies and 8
commit messages. Without a single landing-page document:

- A reviewer landing on, say, PR #175 has no easy way to see that
  it's part of a larger coordinated change set, or that the
  `[spec].version` bump conflicts with PR #170's bump.
- Tooling (PR-batching bots, change-impact analyzers,
  launch-scaffolder regenerators) has nothing to introspect; each
  bot would have to re-parse 8 PR descriptions.
- Future audits need an entry point — `docs/audits/` already follows
  the dated-audit pattern (`dogfooding-matrix-2026-04-04.md`,
  `gap-matrix-2026-04-17.a2ml`); this matches.

## Pattern conformance

- Files in `docs/audits/` matches the existing convention.
- A2ML extension syntax (`@abstract:` block) matches
  `gap-matrix-2026-04-17.a2ml`. Pure `tomllib` does not parse A2ML;
  the repo's A2ML tooling does.
- SPDX headers on both files.

## Coordination

- Independent of the 8 review PRs — touches only `docs/audits/`,
  no overlap with `launcher/` or `docs/UX-standards/`.
- Lock-step gate (#172) does NOT fire on this PR (touches neither
  `launcher-standard.a2ml` nor `launcher-standard.adoc`).
- Final PR in the campaign. After this lands, the campaign is fully
  documented and merge-sequenceable purely from `main` artefacts.

## Test plan

- [x] adoc structure: 7 top-level sections (`==`) render under
      `asciidoctor` (visual)
- [x] a2ml structure: 8 `[[pr]]` array entries, `[campaign]`,
      `[coordination]`, `[deferred-followups]` with 2 `[[deferred]]`
      items, `[session-lessons-captured]`, `[provenance]` — all
      present and consistent
- [x] All 8 PR numbers in the manifest match the actually-filed PRs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>